From ad349caa0013996c65b4263c808b0cc5437accfa Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sun, 6 Dec 2015 14:27:40 -0500 Subject: [PATCH] gadget: Add some documentation --- gtk/gtkcsscustomgadget.c | 109 +++++++++++++++++++++++++++++++++++++++ gtk/gtkcssgadget.c | 98 +++++++++++++++++++++++++++++++++++ 2 files changed, 207 insertions(+) diff --git a/gtk/gtkcsscustomgadget.c b/gtk/gtkcsscustomgadget.c index 1dcc5a3265..d627a1904f 100644 --- a/gtk/gtkcsscustomgadget.c +++ b/gtk/gtkcsscustomgadget.c @@ -23,6 +23,77 @@ #include "gtkcssnodeprivate.h" +/* + * GtkCssCustomGadget is a subclass that lets widgets customize size + * requests, size allocation and drawing of gadgets. The gadget is passed + * to the callbacks as the first argument, and you can use gtk_css_gadget_get_owner() + * to obtain the widget. Note that the widgets style context is not saved, + * so if you want to query style properties or call gtk_render functions which + * take the style context as an argument, you should use + * gtk_style_context_save_to_node to make the gadget's CSS node take effect. + * + * The callbacks are + * + * GtkCssPreferredSizeFunc: + * @gadget: the #GtkCssCustomGadget + * @orientation: whether a width (ie horizontal) or height (ie vertical) is requested + * @for_size: the available size in the opposite direction, or -1 + * @minimum: return location for the minimum size + * @natural: return location for the natural size + * @minimum_baseline: (nullable): return location for the baseline at minimum size + * @natural_baseline: (nullable): return location for the baseline at natural size + * @data: data provided when registering the callback + * + * The GtkCssPreferredSizeFunc is called to determine the content size in + * gtk_css_gadget_get_preferred_size(). @for_size is a content size (ie excluding + * CSS padding, border and margin) and the returned @minimum, @natural, + * @minimum_baseline, @natural_baseline should be content sizes excluding CSS + * padding, border and margin as well. + * + * Typically, GtkCssPreferredSizeFunc will query the size of sub-gadgets and + * child widgets that are placed relative to the gadget and determine its own + * needed size from the results. If the gadget has no sub-gadgets or child + * widgets that it needs to place, then a GtkCssPreferredSizeFunc is only + * needed if you want to enforce a minimum size independent of CSS min-width + * and min-height (e.g. if size-related style properties need to be supported + * for compatibility). + * + * GtkCssAllocateFunc: + * @gadget: the #GtkCssCustomGadget + * @allocation: the allocation + * @baseline: the baseline + * @out_clip: (out): return location for the content clip + * @data: data provided when registering the callback + * + * The GtkCssAllocateFunc is called to allocate the gadgets content in + * gtk_css_gadget_allocate(). @allocation and @baseline are content sizes + * (ie excluding CSS padding, border and margin). + * + * Typically, GtkCssAllocateFunc will allocate sub-gadgets and child widgets + * that are placed relative to the gadget, and merge their clips into the + * value returned as @out_clip. For clip handling in the main gadget of + * containers, gtk_container_get_children_clip() can be useful. Gadgets that + * don't have sub-gadgets of child widgets don't need a GtkCssAllocateFunc + * (although it is still required to call gtk_css_gadget_allocate() on them). + * + * GtkCssDrawFunc: + * @gadget: the #GtkCssCustomGadget + * @cr: the cairo context to draw on + * @x: the x origin of the content area + * @y: the y origin of the content area + * @width: the width of the content area + * @height: the height of the content area + * @data: data provided when registering the callback + * + * The GtkCssDrawFunc is called to draw the gadgets content in + * gtk_css_gadget_draw(). It gets passed an untransformed cairo context + * and the coordinates of the area to draw the content in. + * + * Typically, GtkCssDrawFunc will draw sub-gadgets and child widgets + * that are placed relative to the gadget, as well as custom content + * such as icons, checkmarks, arrows or text. + */ + typedef struct _GtkCssCustomGadgetPrivate GtkCssCustomGadgetPrivate; struct _GtkCssCustomGadgetPrivate { GtkCssPreferredSizeFunc preferred_size_func; @@ -117,6 +188,27 @@ gtk_css_custom_gadget_init (GtkCssCustomGadget *custom_gadget) } +/** + * gtk_css_custom_gadget_new_for_node: + * @node: the #GtkCssNode to use for the gadget + * @owner: the widget that the gadget belongs to + * @preferred_size_func: (nullable): the GtkCssPreferredSizeFunc to use + * @allocate_func: (nullable): the GtkCssAllocateFunc to use + * @draw_func: (nullable): the GtkCssDrawFunc to use + * @data: (nullable): user data to pass to the callbacks + * @destroy_func: (nullable): destroy notify for @data + * + * Creates a #GtkCssCustomGadget for an existing CSS node. + * This function is typically used in the widgets init function + * to create the main gadget for the widgets main CSS node (which + * is obtained with gtk_widget_get_css_node()), as well as other + * permanent sub-gadgets. Sub-gadgets that only exist sometimes + * (e.g. depending on widget properties) should be created and + * destroyed as needed. All gadgets should be destroyed in the + * finalize (or dispose) vfunc. + * + * Returns: (transfer full): the new gadget + */ GtkCssGadget * gtk_css_custom_gadget_new_for_node (GtkCssNode *node, GtkWidget *owner, @@ -145,6 +237,23 @@ gtk_css_custom_gadget_new_for_node (GtkCssNode *node, return result; } +/** + * gtk_css_custom_gadget_new: + * @name: the name for the CSS node + * @owner: the widget that the gadget belongs to + * @parent: the gadget that has the parent CSS node + * @next_sibling: the gadget that has the sibling CSS node + * @preferred_size_func: (nullable): the GtkCssPreferredSizeFunc to use + * @allocate_func: (nullable): the GtkCssAllocateFunc to use + * @draw_func: (nullable): the GtkCssDrawFunc to use + * @data: (nullable): user data to pass to the callbacks + * @destroy_func: (nullable): destroy notify for @data + * + * Creates a #GtkCssCustomGadget with a new CSS node which gets + * placed below the @parent's and before the @next_sibling's CSS node. + * + * Returns: (transfer full): the new gadget + */ GtkCssGadget * gtk_css_custom_gadget_new (const char *name, GtkWidget *owner, diff --git a/gtk/gtkcssgadget.c b/gtk/gtkcssgadget.c index 60bb9d2a8c..b3bf1c607d 100644 --- a/gtk/gtkcssgadget.c +++ b/gtk/gtkcssgadget.c @@ -31,6 +31,34 @@ #include "gtkrenderbackgroundprivate.h" #include "gtkrenderborderprivate.h" +/* + * Gadgets are 'next-generation widgets' - they combine a CSS node + * for style matching with geometry management and drawing. Each gadget + * corresponds to 'CSS box'. Compared to traditional widgets, they are more + * like building blocks - a typical GTK+ widget will have multiple gadgets, + * for example a check button has its main gadget, and sub-gadgets for + * the checkmark and the text. + * + * Gadgets are not themselves hierarchically organized, but it is common + * to have a 'main' gadget, which gets used by the widgets size_allocate, + * get_preferred_width, etc. and draw callbacks, and which in turn calls out + * to the sub-gadgets. This call tree might extend further if there are + * sub-sub-gadgets that a allocated relative to sub-gadgets. In typical + * situations, the callback chain will reflect the tree structure of the + * gadgets CSS nodes. + * + * Geometry management - Gadgets implement much of the CSS box model for you: + * margins, border, padding, shadows, min-width/height are all applied automatically. + * + * Drawing - Gadgets implement standardized CSS drawing for you: background, + * shadows and border are drawn before any custom drawing, and the focus outline + * is (optionally) drawn afterwards. + * + * Invalidation - Gadgets sit 'between' widgets and CSS nodes, and connect + * to the nodes ::style-changed signal and trigger appropriate invalidations + * on the widget side. + */ + typedef struct _GtkCssGadgetPrivate GtkCssGadgetPrivate; struct _GtkCssGadgetPrivate { GtkCssNode *node; @@ -261,6 +289,14 @@ gtk_css_gadget_init (GtkCssGadget *gadget) } +/** + * gtk_css_gadget_get_node: + * @gadget: a #GtkCssGadget + * + * Get the CSS node for this gadget. + * + * Returns: (transfer none): the CSS node + */ GtkCssNode * gtk_css_gadget_get_node (GtkCssGadget *gadget) { @@ -269,6 +305,14 @@ gtk_css_gadget_get_node (GtkCssGadget *gadget) return priv->node; } +/** + * gtk_css_gadget_get_style: + * @gadget: a #GtkCssGadget + * + * Get the CSS style for this gadget. + * + * Returns: (transfer none): the CSS style + */ GtkCssStyle * gtk_css_gadget_get_style (GtkCssGadget *gadget) { @@ -277,6 +321,14 @@ gtk_css_gadget_get_style (GtkCssGadget *gadget) return gtk_css_node_get_style (priv->node); } +/** + * gtk_css_gadget_get_style: + * @gadget: a #GtkCssGadget + * + * Get the widget to which this gadget belongs. + * + * Returns: (transfer none): the widget to which @gadget belongs + */ GtkWidget * gtk_css_gadget_get_owner (GtkCssGadget *gadget) { @@ -285,6 +337,13 @@ gtk_css_gadget_get_owner (GtkCssGadget *gadget) return priv->owner; } +/** + * gtk_css_gadget_add_class: + * @gadget: a #GtkCssGadget + * @name: class name to use in CSS matching + * + * Adds a style class to the gadgets CSS node. + */ void gtk_css_gadget_add_class (GtkCssGadget *gadget, const char *name) @@ -297,6 +356,13 @@ gtk_css_gadget_add_class (GtkCssGadget *gadget, gtk_css_node_add_class (priv->node, quark); } +/** + * gtk_css_gadget_remove_class: + * @gadget: a #GtkCssGadget + * @name: class name + * + * Removes a style class from the gadgets CSS node. + */ void gtk_css_gadget_remove_class (GtkCssGadget *gadget, const char *name) @@ -353,6 +419,24 @@ get_box_padding (GtkCssStyle *style, border->right = get_number (style, GTK_CSS_PROPERTY_PADDING_RIGHT); } +/** + * gtk_css_gadget_get_preferred_size: + * @gadget: the #GtkCssGadget whose size is requested + * @orientation: whether a width (ie horizontal) or height (ie vertical) size is requested + * @for_size: the available size in the opposite direction, or -1 + * @minimum: (nullable): return location for the minimum size + * @natural: (nullable): return location for the natural size + * @minimum_baseline: (nullable): return location for the baseline at minimum size + * @natural_baseline: (nullable): return location for the baseline at natural size + * + * Gets the gadgets minimum and natural size (and, optionally, baseline) + * in the given orientation for the specified size in the opposite direction. + * + * The returned values include CSS padding, border and margin in addition to the + * gadgets content size, and respect the CSS min-with or min-height properties. + * + * The @for_size is assumed to include CSS padding, border and margins as well. + */ void gtk_css_gadget_get_preferred_size (GtkCssGadget *gadget, GtkOrientation orientation, @@ -419,6 +503,20 @@ gtk_css_gadget_get_preferred_size (GtkCssGadget *gadget, *natural_baseline += extra_baseline; } +/** + * gtk_css_gadget_allocate: + * @gadget: the #GtkCssGadget to allocate + * @allocation: the allocation + * @baseline: the baseline for the allocation + * @out_clip: (out): return location for the gadgets clip region + * + * Allocates the gadget. + * + * The @allocation is assumed to include CSS padding, border and margin. + * The gadget content will be allocated a smaller area that excludes these. + * The @out_clip includes the shadow extents of the gadget in addition to + * any content clip. + */ void gtk_css_gadget_allocate (GtkCssGadget *gadget, const GtkAllocation *allocation, -- 2.30.2